Bulk Detach Subscriber Package

The Bulk Detach Subscriber Package API is used to detach existing packages from multiple subscribers in a single call. The system allows detaching a customer package ('Sell Package') from sub-customers' subscribers in a standard manner, or detaching a package created by the parent customer ('Buy Package') from its own subscribers in a self-service manner. The use of the self-service detach mode is permitted only if the parent customer has granted permission to the specific sub-customer by enabling the 'allowOfferDelegation' flag and if the sub-customer is listed in the 'eligibleSubAccountIds' attribute of the attached package. Detachment is a soft deletion; however, once executed, it cannot be recovered. If required, the (Bulk) Attach Subscriber Offer API should be used.

Method	Path
POST	/api/v2/bulk/subscriber/package/detach

Eligibility

The requestor is eligible to detach a package from their sub-customers’ subscribers. However, they are not allowed to detach a package from their own subscribers unless the requestor's parent customer:

Has granted permission by enabling the 'allowOfferDelegation' parameter.
Has included them in the attached package’s 'eligibleSubAccountIds' attribute.

API Request

Request Structure

Parameter	Type	M/O/CM	Description
bulk	Object	M	Array of the main request body object.

Bulk

Parameter	Type	M/O/CM	Description
subscriberIdentifiers	Object	M	Subscriber unique keys object; defines the search criteria.
content	Object	M	Main elements container object.

subscriberIdentifiers

Parameter	Type	M/O/CM	Description
type	String	M	Defines the search criteria. Valid type ENUMs are: ‘IMSI’, ‘ICCID’, ‘MSISDN’, ‘IMEI’, ‘IMEISV’.
value	String	M	Type value. IMSI, ICCID, MSISDN, IMEI, or IMEISV number.

Content

Parameter	Type	M/O/CM	Description
packageId	UUID	M	Catalog package ID.
myPackage	Boolean	O	Determines whether to detach one of the customer’s packages (Sell Packages) from sub-account subscribers or one of the customer’s parent packages (Buy Packages) from own subscribers. True = Request to detach a parent package (my package) from own subscribers. This ‘self-service’ functionality is allowed only if the sub-customer has been defined by its parent customer as allowed to delegate parent customer packages (allow_offer_delegation = true). False = Request to detach one of the customer's packages (Sell Packages) from sub-account subscribers (normal operation). Default if not provided is ‘false’.

Parameter

Type

M/O/CM

Description

packageId

UUID

Catalog package ID.

myPackage

Boolean

Determines whether to detach one of the customer’s packages (Sell Packages) from sub-account subscribers or one of the customer’s parent packages (Buy Packages) from own subscribers.

True = Request to detach a parent package (my package) from own subscribers. This ‘self-service’ functionality is allowed only if the sub-customer has been defined by its parent customer as allowed to delegate parent customer packages (allow_offer_delegation = true).
False = Request to detach one of the customer's packages (Sell Packages) from sub-account subscribers (normal operation).

Default if not provided is ‘false’.

API Response

Response Structure

Parameter	Type	M/O/CM	Description
bulk	Object	M	Array of the main response body object.
pageable	Object	O	Paging information object. Displayed when an API call is successful. For a failure, it will be empty.

Bulk

Parameter	Type	M/O/CM	Description
errorCode	String	O	Failure code.
errorMessage	String	O	Failure detailed description.
requestId	UUID	CM	Request instance ID. To be used by external systems to query the call (operation) status, whether in progress, successful, or failed. Displayed when an API call is successful. For a failure, it will be empty.
subscriberIdentifiers	Object	M	Subscriber unique keys object; defines the search criteria.
content	Object	M	Main response body object. Reflects a single node of the original request.

subscriberIdentifiers

Parameter	Type	M/O/CM	Description
type	String	M	Defines the search criteria. Valid type ENUMs are: 'IMSI', 'ICCID', 'MSISDN', 'IMEI', 'IMEISV'.
value	String	M	Type value. IMSI, ICCID, MSISDN, IMEI, or IMEISV number.

Content

Parameter	Type	M/O/CM	Description
packageId	UUID	M	Catalog package ID.
myOffer	Boolean	M	Determines whether to attach one of the customer’s plans (Sell Plans) to sub-account subscribers or one of the customer’s parent plans (Buy Plans) to own subscribers. True = Request to attach a parent plan (Buy Plan) to own subscribers. False = Request to attach one of the customer’s plans (Sell Plan) to sub-account subscribers (normal operation). Default if not provided is ‘false’.

Parameter

Type

M/O/CM

Description

packageId

UUID

Catalog package ID.

myOffer

Boolean

Determines whether to attach one of the customer’s plans (Sell Plans) to sub-account subscribers or one of the customer’s parent plans (Buy Plans) to own subscribers.

True = Request to attach a parent plan (Buy Plan) to own subscribers.
False = Request to attach one of the customer’s plans (Sell Plan) to sub-account subscribers (normal operation).

Default if not provided is ‘false’.

Pageable

Parameter	Type	M/O/CM	Description
page	Numeric	M	Page number.
size	Numeric	M	Page size. Number of requested elements per page.
totalPages	Numeric	M	Total amount of available pages per requested page size.
totalElements	Numeric	M	Total amount of retrieved elements.

Error Codes

In addition to the general success and failure codes, the following error codes are possible per each of the ‘Bulk’ array elements:

Code	Message
GLOBAL_1001	Service unavailable. Please try again.
SUBSCRIBER_1059	Failed to detach a package.
AUTH_1020	You are not allowed to detach parent customer packages from your own SIM cards.

Examples

Request Body

Copy

{
  "bulk": [
    {
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961859"
      },
      "content": {
        "packageId": "4543dedb-cce7-4bee-89f3-7af1447927e6"
      }
    },
    {
      "subscriberIdentifiers": {
        "type": "ICCID",
        "value": "8935711001000034535"
      },
      "content": {
        "packageId": "e7fcef24-5c03-41dd-9e33-995b7d6f47e2",
        "myPackage": true
      }
    }
  ]
}

Response Body Success ACK

Copy

{
  "bulk": [
    {
      "errorCode": "",
      "errorMessage": "",
      "requestId": "ff74dca6-8e7f-4b85-a42b-13860913b370",
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961963"
      },
      "content": {
        "subscriberOfferingId": "4543dedb-cce7-4bee-89f3-7af1447927e6",
        "myOffer": false
      }
    },
    {
      "errorCode": "",
      "errorMessage": "",
      "requestId": "7e74dce6-8eef-4c86-a4bb-1a860913c271",
      "subscriberIdentifiers": {
        "type": "ICCID",
        "value": "8935711001000035687"
      },
      "content": {
        "subscriberOfferingId": "e7fcef24-5c03-41dd-9e33-995b7d6f47e2",
        "myOffer": true
      }
    }
  ],
  "pageable": {
    "page": 0,
    "size": 10,
    "totalPages": 1,
    "totalElements": 1
  }
}

Response Body Includes Failure\s NAK

Copy

{
  "bulk": [
    {
      "errorCode": "AUTH_1013",
      "errorMessage": "You are not allowed to detach parent customer plans from your own SIM card",
      "requestId": "",
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961963"
      },
      "content": {
        "subscriberOfferingId": "4543dedb-cce7-4bee-89f3-7af1447927e6",
        "myOffer": falsetrue
      }
    }
  ],
  "pageable": {
    "page": 0,
    "size": 10,
    "totalPages": 1,
    "totalElements": 1
  }
}